Skip to content

Strengthen report semantic for API "re-exports"#53

Merged
fantazio merged 2 commits intoLexiFi:masterfrom
fantazio:reduced_lib
Feb 9, 2026
Merged

Strengthen report semantic for API "re-exports"#53
fantazio merged 2 commits intoLexiFi:masterfrom
fantazio:reduced_lib

Conversation

@fantazio
Copy link
Collaborator

@fantazio fantazio commented Feb 2, 2026

When designing a lib, one may want to explictly expose some submodules as part of its API. While doing so, some parts of these submodules may remain hidden from the API but exposed by the submodules for internal use.
Reporting on values in a library API and submodules must remain actionable. Therefore, the semantic is:

  • For a value defined in the submodule, account for all the uses internal to the library but the ones in the submodule itself (unless there is no interface or the --internal option is used, as usual). Among those uses, re-expositions count. I.e. if the value is exposed by the API, then this counts as a use because it is required.
  • For a submodule's value exposed in the API, account for all the uses external to the library.

Uses of an API value is not be propagated to the submodule's value. Only the re-exposition counts as a use.
Hence, a submodule's value explicitly exposed in the API cannot be reported as unused while the API's value may be.

This is coherent with the general value reporting semantic.

When designing a lib, one may want to explictly expose some submodules
as part of its API. While doing so, some parts of these submodules may
remain hidden from the API but exposed by the submodules for internal
use.
Reporting on values in a library API and submodules must remain
actionable. Therefore, the semantic is:
- For a value defined in the submodule, account for all the uses
internal to the library but the ones in the submodule itself (unless
there is no interface or the `--internal` option is used, as usual).
Among those uses, re-expositions count. I.e. if the value is exposed by
the API, then this counts as a use because it is required.
- For a submodule's value exposed in the API, account for all the uses
external to the library.

Uses of an API value must not be propagated to the submodule's value.
This is currently the case e.g. in the threshold-3-0.5 test scenario
which expects `./examples/using_dune/reduced_lib/values.mli:1: used` in
the exported values used 2 times. It is used inside `Value`, and by
requirement for `Reduced_lib.Values` API. Its re-export
(`Reduced_lib.Values.used`) is outside the library in
`examples/using_dune/reduced_lib/values.ml`.

Hence, a submodule's value explicitly exposed in the API cannot be
reported as unused while the API's value may be.

This is coherent with the general value reporting semantic.
A "re-export" uses used to be propagated to the re-exported values. This
propagation is order dependent. That is, all the uses that have been
seen before the propagation happens are propagated, but future
re-exports are not. The propagation was happening during the analysis of
the module that re-exports the value.

To fit the strenghtened semantics, the uses of a re-exported value must
not be propagated. Only the re-export counts as a use. Thanks to this
semantic, the associated reports do not depend on the order in which
files are analyzed anymore.
@fantazio fantazio changed the title Add tests with API "re-exports" Strengthen report semantic for API "re-exports" Feb 9, 2026
@fantazio fantazio merged commit 07408d8 into LexiFi:master Feb 9, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant